Nazwa  : Net
Wersja : 1.0
Opis   : Modu do komunikacji sieciowej
Autor  : Adam Sawicki "Regedit"
Data   : 2004-07-21
URL    : mailto:regedit@risp.pl
URL    : http://www.programex.prv.pl/


Wstp
=====

Net to modu do komunikacji w sieci LAN oraz w Internecie. Stanowi
obiektow otoczk na Windows Sockets.

Uywa:

- STL
- windows.h - koniecznie z poprzedzajcym:

    #define _WIN32_WINNT 0x0400

- pxlib
- myerror
- systemu Callback

Wymaga zlinkowania:

- Ws2_32.lib
- pxlib


Serwer
======

1.
Socket nasuchujcy:

  net::SocketListening *Listener;

2.
Utworzenie:

  Listener = new net::SocketListening;
  // Zakadamy, e ten kod znajduje si w metodzie klasy dziedziczcej z CallbackHandler
  CallbackBind(&Listener->Handler);
  if ( Listener->Init(Port) )
    ...

3.
Zaakceptowanie przychodzcego poczenia:

  // Jestemy w metodzie Callback(CallbackSender *Sender, int Message, void *Params)
  case net::CBM_CONNECT:
    net::CBMConnectStruct *cs = reinterpret_cast<net::CBMConnectStruct*>(Params);
    // Zapamitanie nowego socketa w polu typu net::SocketConnection*
    Connection = cs->NewSocket;
    CallbackBind(&Connection->Handler);


Klient
======

1.
Socket poczeniowy:

  net::SocketConnection *Connection;

2.
Inicjalizacja:

  Connection = new net::SocketConnection;
  CallbackBind(&Connection->Handler);
  if ( Connection->Init(net::addr2in_addr(Address), Port) )
    ...

3.
Udao si nawiza poczenie:

  case net::CBM_CONNECTED:
    ...


Transmisja
==========

1.
Wysanie pakietu danych:

  void Tester::SendPacket()
  {
    Connection->Send_Begin(Size);
    Connection->Send_Add(Buf, SubSize);
    Connection->Send_Add(Buf, SubSize);
    ...
    Connection->Send_End();
  }

Jeli danych do wysania jest mao, mona po prostu pododawa pakiety,
a one trafi do kolejki i bd si wysyay w swoim tempie.

Jeli danych jest duo (np. transmisja pliku), naley wysa pierwszy
pakiet, a nastpne kiedy "co zostao wysane" i kolejka do wysyania jest
pusta:

  void Tester::Send()
  {
    ...
    SendPacket();
  }

  case net::CBM_WRITESTH:
    if (Connection->Send_GetBytesTotal() == 0)
      SendPacket();

2.
Odbieranie pakietu danych:

  case net::CBM_READ:
    net::CBMReadStruct *rs = reinterpret_cast<net::CBMReadStruct*>(Params);
    ... // W strukturze rs jest wskanik do danych pakietu i jego rozmiar

3.
Rozczenie i usunicie socketa:

  delete Connection;


Reakcja na bdy
================

1.
Jeli nie mona nasuchiwa na danym porcie:
Natychamist wysya CBM_ERROR:

  [.\Net.cpp,195] Nie mona zbindowa gniazda do portu: 7779
  (WinSock,10048,WSAEADDRINUSE) Address already in use

2.
Jeli nie mona nawiza poczenia:
Czeka 20s i po tym czasie wysya CBM_ERROR:

  [.\Net.cpp,129] Bd gniazda
  (WinSock,10060,WSAETIMEDOUT) Connection timed out

3.
Jeli po drugiej stronie serwer lub klient elegancko zerwie poczenie:
Natychmiast wysya CBM_DISCONNECT.

4.
Jeli po drugiej stronie serwer lub klient si wysypie:
(Testowane lokalnie przez loopback i przez Internet)
Natychmiast wysya CBM_ERROR:

    [.\Net.cpp,129] Bd gniazda
    (WinSock,10053,WSAECONNABORTED) Software caused connection abort

5.
Jeli serwer lub klient zostanie odczony od Internetu:

- U tego, ktrego odczyo:
  Natychmiast wysya CBM_ERROR:

    [.\Net.cpp,129] Bd gniazda
    (WinSock,10053,WSAECONNABORTED) Software caused connection abort

- U tego po drugiej stronie:
  Wogle nie wie o rozczeniu, trzeba zrobi jaki ping samemu.

6.
Jeli tam gdzie jest serwer lub klient zawiesi si komputer:
Nie sprawdzaem, ale mona si domyla, e po drugiej stronie take nie
bdzie wiadomo wogle, e nastpio rozczenie.


Resolving
=========

Naley utworzy obiekt klasy net::ResolverXXX, zbindowa jego Handler,
wywoa Init i jeli si to uda, oczekiwa na callback. Callbackiem moe
by CBM_RESOLVEXXX lub CBM_ERROR. Po tym jednym callbacku obiekt naley
usun. Mona go te bez zych konsekwencji usun wczeniej, zanim
przyjdzie callback.


Nazwa lub IP -> IP
~~~~~~~~~~~~~~~~~~

  net::ResolverInAddr *R = new net::ResolverInAddr();
  CallbackBind(&R->Handler);
  if ( ResolverInAddr->Init(Name) )
    ...

  case net::CBM_RESOLVEINADDR:
    {
      in_addr *ia = reinterpret_cast<in_addr*>(Params);
      string s = net::in_addr2addr(*ia);
      write("Address resolved to: "+s);
      delete R; R = 0;
    }

Reakcja na bdy:

1.
Nazwa, ktra nie istnieje:
Czeka 2s i zwraca wysya CBM_ERROR:

  [.\net.cpp,154] Nie mona przetworzy nazwy na adres IP
  (WinSock,11001,WSAHOST_NOT_FOUND) Host not found

2.
IP:
Niezalenie czy isniejcy ani wogle czy poprawny - zawsze zwraca ten IP.

3.
Nie ma Internetu:
- IP: i tak zwraca od razu jako ten sam IP
- Nazwa: natychamist wysya CBM_ERROR:

    [.\net.cpp,154] Nie mona przetworzy nazwy na adres IP
    (WinSock,11001,WSAHOST_NOT_FOUND) Host not found

IP -> Nazwa
~~~~~~~~~~~

  net::ResolverName *R = new net::ResolverName();
  CallbackBind(&R->Handler);
  if ( R->Init(ip) )
    ...

  case net::CBM_RESOLVENAME:
    {
      string *s = reinterpret_cast<string*>(Params);
      write("IP resolved to: " + *s);
      delete R; R = 0;
    }

Reakcja na bdy:

1.
Nieisniejcy IP:
Czeka 4s i wysya CBM_ERROR:

  [.\net.cpp,186] Nie mona przetworzy adresu IP na nazw
  (WinSock,11004,WSANO_DATA) Valid name, no data record of requested type

2.
Nie ma Internetu:
Natychamist wysya CBM_EROR:

  [.\net.cpp,186] Nie mona przetworzy adresu IP na nazw
  (WinSock,11004,WSANO_DATA) Valid name, no data record of requested type


Uwaga!
======

Nie usuwa obiektu w kodzie, ktry zosta wywoany bezporednio lub
porednio przez callback od tego obiektu. Moe to powodowa dziwne bdy,
np. tylko w trybuie Release, a w Debug nie itp.
